Node / meshtastic / Meshtastic-Android / files / specs / 006-kmp-project-structure / spec.md

Displaying Rendered • View raw • Download

Feature Branch: T383838020-kmp-project-structure

Created: 2025-07-15

Status: Draft

Input: User description: "Restructure Meshtastic Android project to align with the updated Kotlin Multiplatform recommended project structure"

Cross-Platform Spec: N/A — this is a build/infrastructure change with no user-facing behavior changes across platforms

The Meshtastic Android project should be aligned with the official Kotlin Multiplatform recommended project structure as documented in the KMP project structure guide and the JetBrains blog post on the new KMP default structure. The project already runs on AGP 9.2.1 and already applies the T383838com.android.kotlin.multiplatform.library plugin via convention plugins, but an audit reveals that all 27 KMP modules still contain legacy T383838android {} blocks inside T383838kotlin {} that should be migrated to the recommended T383838kotlin.androidLibrary {} top-level DSL. This effort focuses on completing that migration, validating module boundaries, and ensuring convention plugins enforce the canonical patterns — so the project fully conforms to the new structure with clear module responsibilities.

1. Migrate all legacy T383838android {} blocks inside T383838kotlin {} to the recommended T383838kotlin.androidLibrary {} top-level DSL across all 27 KMP modules in T383838core/ and T383838feature/.

2. Validate and harden convention plugins so that T383838KmpLibraryConventionPlugin and T383838KmpFeatureConventionPlugin configure Android targets exclusively through the new plugin's DSL, preventing legacy patterns from being reintroduced.

3. Confirm entry-point module separation — T383838app/ (Android) and T383838desktop/ (JVM) are already separate entry-point modules with no shared business logic, satisfying the AGP 9 mandatory requirement.

4. Document the module boundary model — map the current T383838core/ (shared logic) and T383838feature/ (shared UI + logic) organization to the recommended T383838sharedLogic / T383838sharedUI categories, confirming they already satisfy the recommended split.

5. Ensure forward compatibility — verify the project structure is compatible with future KMP toolchain updates and potential new targets (iOS, web) without requiring another structural overhaul.

• Introducing iOS, web, or server modules — while the recommended structure supports these, this spec scopes only the existing Android + Desktop targets.

• Renaming modules to match the default template names — the recommended structure uses T383838shared, T383838androidApp, T383838desktopApp as defaults, but the project's existing T383838core/, T383838feature/, T383838app/, T383838desktop/ naming is equally valid and will not be renamed for cosmetic alignment.

• Changing application behavior or UI — this is purely a build infrastructure and module organization change. No user-facing functionality changes.

• Migrating away from existing technology choices — Koin, Ktor, Room KMP, Compose Multiplatform, and Navigation 3 remain as-is per the constitution.

• Migrating T383838feature:widget away from T383838com.android.library — this module is genuinely Android-only (Glance app widgets) and correctly uses the Android library plugin, not the KMP library plugin.

As a contributor, I want the project to build successfully on both Android and Desktop targets after any structural changes, so that my development workflow is uninterrupted.

Why this priority: A broken build blocks all development. This is the absolute minimum bar for any structural change.

Independent Test: Can be fully tested by running T383838./gradlew assembleDebug, T383838./gradlew :desktop:packageUberJarForCurrentOS, and T383838./gradlew allTests and verifying all pass.

Acceptance Scenarios:

1. Given the restructured project, When a developer runs the full Android build (T383838assembleDebug), Then the build completes with zero errors.

2. Given the restructured project, When a developer runs the Desktop build (T383838:desktop:packageUberJarForCurrentOS), Then the build completes with zero errors.

3. Given the restructured project, When a developer runs all tests (T383838allTests), Then all existing tests pass with no regressions.

4. Given the restructured project with T383838DESKTOP_ONLY=true, When a developer builds without Android SDK, Then the desktop-only build succeeds as before.

As a build maintainer, I want the convention plugins in T383838build-logic/ to apply the correct KMP plugin configuration patterns recommended by JetBrains, so that adding new modules follows a clear, documented convention.

Why this priority: Convention plugins are the enforcement layer for project structure. If they are correct, individual module configurations stay consistent.

Independent Test: Can be tested by verifying that T383838KmpLibraryConventionPlugin applies the T383838com.android.kotlin.multiplatform.library plugin and that no KMP library module uses the legacy T383838com.android.library plugin.

Acceptance Scenarios:

1. Given the T383838meshtastic.kmp.library convention plugin, When applied to a KMP module, Then it configures the module using T383838com.android.kotlin.multiplatform.library (not T383838com.android.library).

2. Given the T383838meshtastic.kmp.feature convention plugin, When applied to a feature module, Then it inherits the correct KMP library plugin chain without legacy Android library configuration.

3. Given a new core module is created, When a developer applies T383838meshtastic.kmp.library, Then the module follows the recommended structure with T383838kotlin.androidLibrary {} configuration.

As a new contributor, I want a clear separation between entry-point modules, shared business logic modules, and shared UI modules, so that I know where to add new code based on its purpose.

Why this priority: Clear boundaries reduce onboarding friction and prevent architectural drift over time.

Independent Test: Can be tested by reviewing the module dependency graph and verifying that entry-point modules (T383838app/, T383838desktop/) do not contain shared logic, and that T383838core/ modules do not depend on T383838feature/ modules.

Acceptance Scenarios:

1. Given the module dependency graph, When analyzing T383838app/ dependencies, Then T383838app/ depends on T383838core/ and T383838feature/ modules but contains no shared business logic.

2. Given the module dependency graph, When analyzing T383838desktop/ dependencies, Then T383838desktop/ depends on T383838core/ and T383838feature/ modules but contains no shared business logic.

3. Given any T383838core/ module, When examining its dependencies, Then it does not depend on any T383838feature/ module (unidirectional flow preserved).

As a build maintainer, I want all 27 KMP modules' legacy T383838android {} blocks inside T383838kotlin {} migrated to the recommended T383838kotlin.androidLibrary {} top-level DSL, so that the build configuration fully uses the new plugin's canonical API.

Why this priority: The project already runs AGP 9.2.1 and applies the T383838com.android.kotlin.multiplatform.library plugin, but every KMP module still configures its Android target using the legacy T383838android {} block inside T383838kotlin {} (for namespace, resource settings, etc.). This is the primary gap between the current state and full alignment with the recommended structure. It ties with P1 because the build already works — this is about eliminating technical debt before it becomes a blocker.

Independent Test: Can be tested by searching all T383838core/ and T383838feature/ KMP module T383838build.gradle.kts files for T383838android { blocks inside T383838kotlin {} — zero should remain after migration. All configuration should appear in T383838kotlin.androidLibrary {} top-level blocks or be handled by convention plugins.

Acceptance Scenarios:

1. Given any KMP library module in T383838core/ or T383838feature/, When examining its T383838build.gradle.kts, Then it contains no T383838android {} block inside T383838kotlin {} — Android configuration uses the T383838kotlin.androidLibrary {} top-level DSL or is delegated to convention plugins.

2. Given the T383838configureKotlinMultiplatform() helper in build-logic, When it configures Android targets, Then it uses T383838KotlinMultiplatformAndroidLibraryTarget APIs from the new plugin, not legacy T383838android {} extension configuration.

3. Given the full project with all 27 modules migrated, When building Android and Desktop targets, Then all builds succeed with zero errors.

• What happens when the T383838DESKTOP_ONLY mode is active and no Android SDK is available? The restructured plugins must continue to conditionally skip Android plugin application (as the current T383838isDesktopOnly guard already does).

• How does the system handle modules that are genuinely Android-only (e.g., T383838core:api, T383838core:barcode, T383838screenshot-tests)? These modules should continue using T383838com.android.library or T383838com.android.application as appropriate — the KMP library plugin applies only to multiplatform modules.

• What happens if a module currently uses T383838com.android.library but should be KMP? The migration path must be documented and executed per-module, with build verification at each step.

The audit reveals the project is substantially aligned with the recommended KMP structure, with one significant gap remaining:

T282828

Core modules (19):

T383838core:ble, T383838core:common, T383838core:data, T383838core:database, T383838core:datastore, T383838core:di, T383838core:domain, T383838core:model, T383838core:navigation, T383838core:network, T383838core:nfc, T383838core:prefs, T383838core:proto, T383838core:repository, T383838core:resources, T383838core:service, T383838core:takserver, T383838core:testing, T383838core:ui

Feature modules (8 — excluding widget):

T383838feature:connections, T383838feature:firmware, T383838feature:intro, T383838feature:map, T383838feature:messaging, T383838feature:node, T383838feature:settings, T383838feature:wifi-provision

Not affected (correctly using T383838com.android.library or T383838com.android.application):

T383838app/, T383838desktop/, T383838feature:widget, T383838core:api, T383838core:barcode, T383838screenshot-tests

T282828

The JetBrains blog cites T383838kotlinconf-app, T383838KMP-App-Template, and T383838RSS Reader as reference implementations. The Meshtastic project is more mature and more modularized than any of these, having already decomposed the monolithic T383838shared module into granular T383838core/ and T383838feature/ modules. This is the recommended evolution path for larger projects.

• FR-001: All 27 KMP library modules (T383838core/* except T383838core:api and T383838core:barcode, plus T383838feature/* except T383838feature:widget) MUST have their T383838android {} blocks inside T383838kotlin {} migrated to T383838kotlin.androidLibrary {} top-level DSL blocks.

• FR-002: Entry-point modules (T383838app/, T383838desktop/) MUST remain as standalone application modules that depend on shared modules but contain no reusable business logic. This is already satisfied and MUST NOT regress.

• FR-003: The T383838KmpLibraryConventionPlugin MUST configure Android target properties (namespace, compileSdk, minSdk, resource settings) exclusively through the T383838com.android.kotlin.multiplatform.library plugin's API (T383838KotlinMultiplatformAndroidLibraryTarget), not through legacy T383838android {} extension blocks.

• FR-004: Android-only modules (T383838core:api, T383838core:barcode, T383838feature:widget, T383838screenshot-tests) MUST continue using T383838com.android.library or T383838com.android.application as they are not multiplatform modules.

• FR-005: The T383838DESKTOP_ONLY build mode MUST continue functioning — when active, Android plugin application MUST be skipped for KMP modules (existing T383838isDesktopOnly guard preserved).

• FR-006: Module dependency direction MUST remain unidirectional: T383838app/desktop → feature → core → build-logic. No reverse dependencies.

• FR-007: The T383838configureKotlinMultiplatform() helper function MUST be audited and updated to remove any residual legacy configuration that duplicates or conflicts with the new plugin's target configuration.

• FR-008: Convention plugins MUST prevent future modules from using the legacy T383838android {} pattern — applying T383838meshtastic.kmp.library MUST automatically configure the Android target through the new plugin's DSL with no manual T383838android {} block needed in the module's T383838build.gradle.kts.

• NFR-001: The restructuring MUST NOT increase full-project build time by more than 5%.

• NFR-002: Gradle configuration cache, isolated projects, and parallel execution (T383838gradle.properties settings) MUST remain functional after changes.

• NFR-003: All changes MUST be backward-compatible within a single migration PR — no intermediate broken states on the main branch.

• NFR-004: The migration MUST be documentable as a step-by-step checklist that other Meshtastic platform repositories can reference.

• [x] No PII, location data, or cryptographic keys logged or exposed

• [x] No new network calls that transmit user data

• [x] Proto submodule (T383838core/proto) not modified (read-only upstream)

This feature is purely a build infrastructure change with no runtime behavior changes.

• SC-001: All 27 KMP library modules have zero T383838android {} blocks inside T383838kotlin {} — all Android configuration uses T383838kotlin.androidLibrary {} top-level DSL or is handled by convention plugins.

• SC-002: Full project builds succeed on both Android (T383838assembleDebug) and Desktop (T383838:desktop:packageUberJarForCurrentOS) with zero new errors after migration.

• SC-003: All existing tests pass (T383838allTests) with zero regressions after migration.

• SC-004: The T383838DESKTOP_ONLY build mode continues to function correctly, building without Android SDK.

• SC-005: Build time for a clean T383838assembleDebug does not increase by more than 5% compared to the pre-migration baseline.

• SC-006: A new contributor can add a new KMP module by applying one convention plugin (T383838meshtastic.kmp.library) and the module is correctly configured for both Android and Desktop targets with no manual T383838android {} block needed.

• SC-007: The T383838configureKotlinMultiplatform() helper contains zero references to legacy T383838android {} extension configuration — all Android target configuration goes through the new plugin's API.

• All business logic and UI composables reside in T383838commonMain source set (per Constitution §I, §III).

• The project already runs AGP 9.2.1 and applies T383838com.android.kotlin.multiplatform.library in T383838KmpLibraryConventionPlugin — the plugin adoption is complete; only the DSL migration from T383838android {} to T383838kotlin.androidLibrary {} remains.

• The T383838configureKotlinMultiplatform() helper already uses T383838KotlinMultiplatformAndroidLibraryTarget for compileSdk/minSdk configuration — any remaining legacy T383838android {} blocks are in individual module T383838build.gradle.kts files, not solely in convention plugins.

• No module uses the deprecated T383838androidTarget {} call — this was verified by audit (zero matches found).

• The typical T383838android {} block content in KMP modules is limited to T383838namespace and T383838androidResources.enable = false and occasionally T383838withHostTest {} — migration should be mechanical.

• Android-only modules (T383838core:api, T383838core:barcode, T383838feature:widget) are not candidates for the KMP library plugin migration — they correctly remain on T383838com.android.library.

• The Gradle version catalog (T383838libs.versions.toml) already declares the T383838android-kotlin-multiplatform-library plugin alias pointing to AGP 9.2.1.

• The T383838jvmAndroidMain shared source set pattern (used by some modules via T383838meshtastic.kmp.jvm.android) is compatible with the new plugin and does not conflict with the T383838kotlin.androidLibrary {} DSL.

• The recommended structure's module naming (T383838shared, T383838androidApp, T383838desktopApp) is a default convention, not a requirement — the project's existing T383838core/, T383838feature/, T383838app/, T383838desktop/ naming is equally valid per the JetBrains documentation.